home *** CD-ROM | disk | FTP | other *** search
/ Delphi Developer's Kit 1996 / Delphi Developer's Kit 1996.iso / power / source18 / mapi.txt < prev    next >
Encoding:
Text File  |  1995-12-22  |  8.0 KB  |  234 lines
  1. MAPI Component for Borland Delphi 1.0
  2.  
  3.  
  4. Release Notes
  5.  
  6. Version 0.99
  7.  
  8. This version of the MAPI component for Delphi was developed and has 
  9. been tested under Windows 95 test release build 490, the mail client, 
  10. MSN and the fax service using LAN and RAS connections.
  11.  
  12. Introduction
  13.  
  14. The MAPI component is an easy-to-use, yet powerful piece of software 
  15. that capsulates the set of unhandy SIMPLE MAPI API functions into a 
  16. friendly set of Delphi-style methods and properties.
  17.  
  18. The MAPI component allows you to easily mail-enable your applications 
  19. without requiring any VBX or OCX. It supports up to 255 recipients as 
  20. well as 255 CCÆs (carbon copies) and 255 BCCÆs (blind carbon copies). 
  21. You may attach up to 255 files as well.
  22.  
  23. A main target for development was to expose a fault tolerant interface. 
  24. This means, for example, that you can call any method at any time; if 
  25. a connection could be established, the component intelligently decides 
  26. which steps have to be done to complete the requested task. If you call 
  27. the send method, for example, the component first checks, if a session 
  28. has been established and opens one, if necessary. It then looks into 
  29. the recipient list to find out if you supplied any recipients. If so, 
  30. it validates all entries and calls common dialogs to resolve unknown 
  31. names; otherwise, it opens the address book to let the user select 
  32. recipients. If you didnÆt supply a subject, the component opens the 
  33. common dialog for creating a message.
  34.  
  35. Using the MAPI component
  36.  
  37. Visual Properties
  38.  
  39. KeepConnection (Boolean)
  40.  
  41. If this property is true, the component holds a connection until you 
  42. close it or the component is destroyed. This might be handy if your 
  43. application wants to send more than one message. If false, the 
  44. component shuts down the active MAPI session after a message has been 
  45. sent.
  46.  
  47. MarkRead (Boolean)
  48.  
  49. This property controls if fetched messages should be marked as read or 
  50. not.
  51.  
  52. NewMessagesOnly (Boolean)
  53.  
  54. This property tells the component, if calls to FirstMessage or 
  55. NextMessage should return all messages in the inbox or only new 
  56. (unread) messages.
  57.  
  58. WizardMode (Boolean)
  59.  
  60. If this property is true, the component intelligently opens common 
  61. dialogs to complete the information necessary to send a message. If 
  62. false, the component raises errors if the information for the requested 
  63. task is incomplete.
  64.  
  65.  
  66. Runtime Properties
  67.  
  68. MessageClass (String)
  69.  
  70. This property sets a message class filter for sending and receiving 
  71. custom messages. If you wish to process normal (interpersonal) mail, 
  72. leave this property blank.
  73.  
  74. Originator (String)
  75.  
  76. This property contains the originatorÆs name after you fetched a 
  77. specific message using NextMessage. It has no effect when sending 
  78. mails.
  79.  
  80. Subject (String)
  81.  
  82. Subject (header) of the message. This property is used when sending 
  83. and reading mail. If this property is blank when you call the Send 
  84. method and wizard mode is active , a common new mail-dialog will be 
  85. presented, because a mail without subject is bad style.
  86.  
  87. DateReceived (String)
  88.  
  89. This property contains the date and time of a received message when 
  90. a specific message has been fetched by FirstMessage or NextMessage. 
  91. It is ignored when sending a message.
  92.  
  93. Text (TStringList)
  94.  
  95. This property holds the message text (body) of a message, that has 
  96. been read or is to be sent. Please note that for performance reasons 
  97. the methods FirstMessage and NextMessage do not retrieve 
  98. the message body. You must call the GetMessage method in order to have 
  99. access to the message body.
  100.  
  101. RecipientList (TStringList)
  102.  
  103. This dynamic string array contains the names of all recipients of a 
  104. retrieved or prepared message. You may fill in names code-driven into 
  105. this property or call the AddressBook method to define recipients. If 
  106. you supply the recipients by code the component verifies each entry 
  107. before sending the message.
  108.  
  109. CCList (TStringList)
  110.  
  111. Same as recipient list for carbon copy recipients.
  112.  
  113. BCCList (TStringList)
  114.  
  115. Same as recipient list for blind carbon copy recipients.
  116.  
  117. hasFiles (Boolean)
  118.  
  119. Indicates if a fetched message contains attached files. This property 
  120. is ignored when sending messages.
  121.  
  122. FileList (TStringList)
  123.  
  124. This list holds the full path names of all attached files of a 
  125. retrieved or prepared message. Please note that for performance reasons 
  126. the methods FirstMessage and NextMessage do not retrieve the list 
  127. of attached files. You must call the GetMessage method in order to 
  128. have access to the attached files.
  129.  
  130.  
  131. EOF
  132.  
  133. This property indicates that the last message has been fetched using 
  134. the method NextMessage and allows you to control a fetch loop like 
  135. this:
  136.  
  137.   FirstMessage;
  138.   while not MAPI1.EOF do begin
  139.     <assing msg properties to visual controls or variables>
  140.     NextMessage;
  141.   end;
  142.  
  143. Please note that the call to NextMessage that sets EOF to true does 
  144. not deliver a valid message anymore.
  145.  
  146. Methods
  147.  
  148. Open
  149.  
  150. Logs you on to the mail postoffice. It is not necessary to call this 
  151. method because the component calls it by itself when necessary.
  152.  
  153. Close
  154.  
  155. Shuts down an active mail session. You do not have to call this method 
  156. explicitly because the component calls it when your application exits.
  157.  
  158. AddressBook
  159.  
  160. Opens the common address book dialog.
  161.  
  162. Send
  163.  
  164. Sends a prepared mail. If WizardMode is active, you do not have to 
  165. supply all necessary information for sending a message. The component 
  166. will ask you for the missing information automatically. Otherwise, 
  167. exceptions are generated for each missing item.
  168.  
  169. Clear
  170.  
  171. Clears all message properties.  You typically call this method before 
  172. preparing a new message.
  173.  
  174. FirstMessage
  175.  
  176. Reads the header information of the first message. The property 
  177. NewMessagesOnly decides if all or only new (unread) messages are 
  178. fetched. Please note that this function is relatively slow. This is 
  179. not due to poor implementation (this method calls MAPIFindNext 
  180. straightforward); in fact, mail clients like MS Mail buffer retrieved 
  181. messages locally and fetch only new messages. It is recommended to 
  182. use it the same way, if you intend to write your own mail client.
  183.  
  184.  
  185. NextMessage
  186.  
  187. Reads the header information of the next message. The property 
  188. NewMessagesOnly decides, if all or only new (unread) messages are 
  189. fetched. You may use the methods FirstMessage and NextMessage the 
  190. following way:
  191.  
  192. FirstMessage;
  193.   while not MAPI1.EOF do begin
  194.     <assing msg properties to visual controls or variables>
  195.     NextMessage;
  196.   end;
  197.  
  198. Please note that the call to NextMessage that sets EOF to true does 
  199. not deliver a valid message anymore and that this function is 
  200. relatively slow. This is not due to poor implementation (this method 
  201. calls MAPIFindNext straightforward); in fact, mail clients like MS 
  202. mail buffer retrieved messages locally and fetch only new messages. 
  203. It is recommended to use it the same way, if you intend to write your 
  204. own mail client.
  205.  
  206. GetMessage(iMessage: Integer)
  207.  
  208. This message gets the full information of a previously fetched message. 
  209. After this call, all properties, including Text and FileList (if 
  210. hasFiles is True) are available. You must pass the index of a retrieved 
  211. message ( i.e.using FirstMessage or NextMessage) to this method in 
  212. order to identify a specific message. If you fill all message headers 
  213. into a list box, for example, a call to this method could look like 
  214. this:
  215.  
  216. procedure Tform1.ListBox1DblClick(Sender: TObject);
  217. begin
  218.   MAPI1.GetMessage(ListBox1.ItemIndex);
  219.   <Assign MAPI properties to controls or variables>
  220. end;
  221.  
  222. DeleteMessage(iMessage: Integer)
  223.  
  224. This message deletes a message permanently from the message store. You 
  225. must pass the index of a retrieved message ( i.e.using FirstMessage or 
  226. NextMessage) to this method in order to identify a specific message.
  227.  
  228.  
  229. This component is still in beta stadium. I intend to release it for 
  230. about 15 US$ as soon as it is stable enough. I would be pleased to hear 
  231. your comments, critics and bug reports. Currently, IÆm reachable  
  232. through the Microsoft Network as Christian Salzmann.
  233.  
  234.